[py] Fix docstring issues that sphinx complains about by cgoldberg · Pull Request #15466 · SeleniumHQ/selenium

cgoldberg · 2025-03-20T21:41:27Z

User description

Motivation and Context

This is a bunch of small fixes to docstrings that sphinx keeps complaining about when generating the Python docs. There are still a ton of warnings when building the docs, but this at least fixes some of them.

This also includes some minor changes suggested by the bot below in comments.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist

I have read the contributing document.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.

PR Type

Documentation

Description

Fixed inconsistent docstring formatting across multiple files.
Standardized section headers in docstrings for better Sphinx compatibility.
Improved clarity and consistency in parameter and return descriptions.

Changes walkthrough 📝

Relevant files

Documentation

15 files

action_builder.py `Standardized docstring headers for methods.`	+5/-5
by.py `Fixed docstring formatting for class attributes.`	+1/-1
options.py `Standardized docstring headers and usage examples.`	+78/-78
print_page_options.py `Improved docstring formatting for print options.`	+68/-68
proxy.py `Fixed docstring formatting for proxy settings.`	+40/-40
timeouts.py `Standardized docstring headers for timeout descriptors.`	+10/-10
options.py `Standardized docstring headers for IE options.`	+68/-68
shadowroot.py `Fixed docstring formatting for shadow root methods.`	+2/-2
webdriver.py `Standardized docstring headers for WebDriver methods.`	+29/-29
webelement.py `Improved docstring formatting for WebElement methods.`	+9/-9
options.py `Standardized docstring headers for Safari options.`	+12/-12
expected_conditions.py `Fixed docstring formatting for expected conditions.`	+31/-31
relative_locator.py `Standardized docstring headers for relative locator methods.`	+8/-8
wait.py `Improved docstring formatting for wait methods.`	+3/-3
index.rst `Fixed minor formatting issue in documentation index.`	+1/-1

Need help?
Type /help how to ... in the comments thread for any questions about Qodo Merge usage.
Check out the documentation for more information.

qodo-code-review · 2025-03-20T21:42:06Z

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review Formatting Inconsistency The formatting for the Usage and Parameters sections in the script timeout docstring is inconsistent with other sections. The plus signs are missing before the section headers. Usage: ------ - Get - `self.script` - Set - `self.script` = `value` Parameters: ----------- `value`: `float` Documentation Error The socks_username property docstring incorrectly states it "Gets and Sets socks_password" instead of "socks_username". """Gets and Sets `socks_password` Usage: ------ - Get - `self.socks_password` - Set - `self.socks_password` = `value` Parameters: ----------- `value`: `str` """

qodo-code-review · 2025-03-20T21:42:24Z

PR Code Suggestions ✨

Latest suggestions up to 2fe8e77

Category	Suggestion	Impact
General	Fix incorrect return type The return type in the docstring for `web_socket_url` getter is incorrectly specified as `bool` when it should be `str` or `None` to match the parameter type and actual implementation. py/selenium/webdriver/common/options.py [399-417] web_socket_url = _BaseOptionsDescriptor("webSocketUrl") """Gets and Sets WebSocket URL. Usage: ------ - Get - `self.web_socket_url` - Set - `self.web_socket_url` = `value` Parameters: ----------- `value`: `str` Returns: -------- - Get - - `bool` + - `str` or `None` - Set + - `None` """ `[To ensure code accuracy, apply this suggestion manually]` Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a documentation error where the return type for the web_socket_url getter is incorrectly specified as 'bool' when it should be 'str' or 'None' to match the parameter type. This is an important fix for API documentation accuracy.	Medium
More

Previous suggestions

✅ Suggestions up to commit 9b4b273

Category	Suggestion	Impact
General	✅ ~~Fix incorrect docstring description~~ The docstring for `web_socket_url` incorrectly states it's for accepting insecure certificates. It should describe WebSocket URL functionality instead. py/selenium/webdriver/common/options.py [287-288] web_socket_url = _BaseOptionsDescriptor("webSocketUrl") -"""Gets and Set whether the session accepts insecure certificates. +"""Gets and Sets WebSocket URL. `[Suggestion has been applied]` Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a significant error in the docstring where the WebSocket URL property is incorrectly described as controlling insecure certificates acceptance. This is a clear documentation bug that could mislead developers.	Medium
General	✅ ~~Fix incorrect parameter type~~ Suggestion Impact: The commit changed the parameter type in the documentation from bool to str as suggested. It also fixed the description of the web_socket_url property. code diff: - """Gets and Set whether the session accepts insecure certificates. + """Gets and Sets WebSocket URL. Usage: ------ @@ -430,7 +430,7 @@ Parameters: ----------- - `value`: `bool` + `value`: `str` The parameter and return type for `web_socket_url` are incorrectly documented as `bool` when they should be `str` based on the property name and its usage. py/selenium/webdriver/common/options.py [421-439] web_socket_url = _BaseOptionsDescriptor("webSocketUrl") """Gets and Sets WebSocket URL. Usage: ------ - Get - `self.web_socket_url` - Set - `self.web_socket_url` = `value` Parameters: ----------- -`value`: `bool` +`value`: `str` Returns: -------- - Get - - `bool` + - `str` - Set - `None` """ Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the parameter and return types for web_socket_url are incorrectly documented as boolean when they should be strings. This is an important documentation fix that prevents confusion about the expected data types.	Medium
Possible issue	✅ ~~Remove duplicate property declaration~~ Suggestion Impact: The commit removed the first instance of the web_socket_url property declaration (lines 5-25 in the diff), which was one of the duplicates identified in the suggestion. The suggestion wanted to remove the second instance, but the commit removed the first one instead, achieving the same goal of eliminating the duplication. code diff: - web_socket_url = _BaseOptionsDescriptor("webSocketUrl") - """Gets and Set whether the session accepts insecure certificates. - - Usage: - ------ - - Get - - `self.web_socket_url` - - Set - - `self.web_socket_url` = `value` - - Parameters: - ----------- - `value`: `str` - - Returns: - -------- - - Get - - `str` or `None` - - Set - - `None` - """ The web_socket_url property is duplicated in the BaseOptions class. There are two identical property declarations at lines 287 and 421, which could cause confusion or unexpected behavior. py/selenium/webdriver/common/options.py [421-441] -web_socket_url = _BaseOptionsDescriptor("webSocketUrl") -"""Gets and Sets WebSocket URL. +# Remove the duplicate declaration, keeping only one instance of web_socket_url -Usage: ------- -- Get - - `self.web_socket_url` -- Set - - `self.web_socket_url` = `value` - -Parameters: ------------ -`value`: `bool` - -Returns: --------- -- Get - - `bool` -- Set - - `None` -""" - `[Suggestion has been applied]` Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a duplicate declaration of the web_socket_url property in the BaseOptions class. This duplication (at lines 287-305 and 421-440) could lead to unexpected behavior as the second declaration would override the first one. Removing the duplicate is critical for proper class functionality.	High

✅ Suggestions up to commit b5b4e01

Category	Suggestion	Impact
General	✅ ~~Fix inconsistent docstring formatting~~ Suggestion Impact: The commit implemented the exact change suggested, adding one more dash to the 'Example:' section underline to make it consistent with the 'Parameters:' section code diff: - ------- + -------- The indentation in the docstring is inconsistent. The "Example:" section has one less dash than the "Parameters:" section, which could cause issues with Sphinx documentation generation. py/selenium/webdriver/remote/webdriver.py [814-824] def set_page_load_timeout(self, time_to_wait: float) -> None: """Sets the amount of time to wait for a page load to complete before throwing an error. Parameters: ----------- time_to_wait : float - The amount of time to wait (in seconds) Example: - ------- + -------- >>> driver.set_page_load_timeout(30) """ Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies an inconsistency in the docstring formatting where the "Example:" section uses 7 dashes (-------) while the "Parameters:" section uses 9 dashes (-----------). This inconsistency could affect documentation generation with tools like Sphinx.	Low

py/selenium/webdriver/common/options.py

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

* [py] Fix docstring errors that sphinx complained about * [py] Fix parameter type for web_socket_url * [py] Remove duplicate web_socket_url from BaseOptions

cgoldberg added 3 commits March 20, 2025 16:47

[py] Fix docs nits

ee486d9

[py] Fix doc nits

94a5d87

[py] Fix docstring errors that sphinx complained about

b5b4e01

qodo-code-review bot added the Review effort 2/5 label Mar 20, 2025

[py] Fix 1 more docstring

9b4b273

qodo-code-review bot reviewed Mar 20, 2025

View reviewed changes

py/selenium/webdriver/common/options.py Outdated Show resolved Hide resolved

cgoldberg and others added 3 commits March 20, 2025 18:45

Update py/selenium/webdriver/common/options.py

aba26f3

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

[py] Fix parameter type for websocket_url

3af1b2b

[py] Remove duplicate web_socket_url from BaseOptions

2fe8e77

cgoldberg merged commit dada4fb into SeleniumHQ:trunk Mar 20, 2025
4 checks passed

cgoldberg deleted the py-fix-docs-again branch March 20, 2025 22:55

This was referenced Sep 12, 2025

Bump the functionaltests group with 8 updates israurreacarballo/DORA#196

Closed

Bump coverlet.collector and 5 others israurreacarballo/DORA#201

Closed

Bump the selenium group with 2 updates 7474/SRC#677

Merged

This was referenced Sep 19, 2025

Bump coverlet.collector and 5 others israurreacarballo/DORA#217

Closed

Bump the functionaltests group with 9 updates israurreacarballo/DORA#225

Closed

Bump coverlet.collector and 5 others israurreacarballo/DORA#228

Closed

This was referenced Oct 1, 2025

Bump coverlet.collector and 5 others israurreacarballo/DORA#230

Closed

Bump Selenium.Support and Selenium.WebDriver rajbos/github-azure-devops-marketplace-extension-news#277

Closed

dependabot bot mentioned this pull request Oct 24, 2025

Bump Selenium.WebDriver from 4.7.0 to 4.37.0 javiertuya/selema#945

Closed

dependabot bot mentioned this pull request Jan 25, 2026

Bump Selenium.WebDriver from 4.27.0 to 4.40.0 pabloFuente/livekit-server-sdk-dotnet#45

Merged

This was referenced Feb 16, 2026

⬆️ Bump Selenium.WebDriver from 4.27.0 to 4.40.0 percy/percy-selenium-dotnet#393

Closed

⬆️ Bump Selenium.WebDriver and System.Text.Json percy/percy-selenium-dotnet#394

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

[py] Fix docstring issues that sphinx complains about#15466

[py] Fix docstring issues that sphinx complains about#15466
cgoldberg merged 7 commits intoSeleniumHQ:trunkfrom
cgoldberg:py-fix-docs-again

cgoldberg commented Mar 20, 2025 •

edited

Loading

Uh oh!

qodo-code-review bot commented Mar 20, 2025

Uh oh!

qodo-code-review bot commented Mar 20, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Comments

Conversation

cgoldberg commented Mar 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Motivation and Context

Types of changes

Checklist

PR Type

Description

Changes walkthrough 📝

Uh oh!

qodo-code-review bot commented Mar 20, 2025

PR Reviewer Guide 🔍

Uh oh!

qodo-code-review bot commented Mar 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Previous suggestions

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cgoldberg commented Mar 20, 2025 •

edited

Loading

qodo-code-review bot commented Mar 20, 2025 •

edited

Loading